home *** CD-ROM | disk | FTP | other *** search
iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) NNNNAAAAMMMMEEEE impOpen, impOpenFd, impOpenBuf, impOpenExt, impOpenFdExt, impOpenBufExt, impClose, impCloseFd - open/close SGI Image Format files SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<iiiimmmmpppp....hhhh>>>> IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnFFFFdddd((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnBBBBuuuuffff((((vvvvooooiiiidddd ****bbbbuuuuffff,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnEEEExxxxtttt((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, IIIIMMMMPPPPCCCCaaaacccchhhheeeeMMMMooooddddeeee ccccaaaacccchhhheeee,,,, ............))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnFFFFddddEEEExxxxtttt((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, IIIIMMMMPPPPCCCCaaaacccchhhheeeeMMMMooooddddeeee ccccaaaacccchhhheeee,,,, ............))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnBBBBuuuuffffEEEExxxxtttt((((vvvvooooiiiidddd ****bbbbuuuuffff,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, ............))));;;; iiiinnnntttt iiiimmmmppppCCCClllloooosssseeee((((IIIIMMMMPPPPIIIImmmmaaaaggggeeee ****iiiimmmmaaaaggggeeee))));;;; iiiinnnntttt iiiimmmmppppCCCClllloooosssseeeeFFFFdddd((((IIIIMMMMPPPPIIIImmmmaaaaggggeeee ****iiiimmmmaaaaggggeeee,,,, iiiinnnntttt ****ffffddddpppp))));;;; In write mode iiiimmmmppppOOOOppppeeeennnn, iiiimmmmppppOOOOppppeeeennnnFFFFdddd, iiiimmmmppppOOOOppppeeeennnnEEEExxxxtttt and iiiimmmmppppOOOOppppeeeennnnFFFFddddEEEExxxxtttt require that these additional parameters be specified: uuuuiiiinnnntttt____tttt rrrraaaasssstttteeeerrrrTTTTyyyyppppeeee,,,, uuuuiiiinnnntttt____tttt ddddiiiimmmmeeeennnnssssiiiioooonnnn,,,, uuuuiiiinnnntttt____tttt xxxxSSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt yyyySSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt nnnnuuuummmmCCCChhhhaaaannnnnnnneeeellllssss,,,, uuuuiiiinnnntttt____tttt iiiimmmmaaaaggggeeeeTTTTyyyyppppeeee,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee where uuuuiiiinnnntttt____tttt stands for uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The _l_i_b_i_m_p library provides a number of different functions to open an SGI Image Format file. The _i_m_p_O_p_e_n, _i_m_p_O_p_e_n_F_d, _i_m_p_O_p_e_n_E_x_t and _i_m_p_O_p_e_n_F_d_E_x_t functions each open an SGI Image Format file for reading or writing. _i_m_p_O_p_e_n opens the image file specified by _f_n_a_m_e. If _m_o_d_e is """"rrrr"""", the file is opened for reading. If _m_o_d_e is """"wwww"""" the file is opened for writing and created if it does not exist or truncated to zero length if it does exist. IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, """"rrrr""""))));;;; IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, """"wwww"""",,,, uuuuiiiinnnntttt____tttt rrrraaaasssstttteeeerrrrTTTTyyyyppppeeee,,,, uuuuiiiinnnntttt____tttt ddddiiiimmmmeeeennnnssssiiiioooonnnn,,,, uuuuiiiinnnntttt____tttt xxxxSSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt yyyySSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt nnnnuuuummmmCCCChhhhaaaannnnnnnneeeellllssss,,,, uuuuiiiinnnntttt____tttt iiiimmmmaaaaggggeeeeTTTTyyyyppppeeee,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;; PPPPaaaaggggeeee 1111 iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) Excess arguments to _i_m_p_O_p_e_n over the above are ignored. _i_m_p_O_p_e_n_F_d opens the image file pointed to by the file descriptor _f_d. The descriptor's permissions must permit the operations specified by _m_o_d_e. That is, if _m_o_d_e is """"wwww"""", the descriptor must have write permission. In addition, it must be possible to seek on the specified descriptor. At this time read/write mode is not supported for SGI Image files. Upon successful execution both functions return a pointer to an SGI Image file structure. If _i_m_p_O_p_e_n or _i_m_p_O_p_e_n_F_d open an image file for writing, a number of additional parameters must be specified. _r_a_s_t_e_r_T_y_p_e Specifies both the raster encoding method and the number of bytes per pixel per channel. SGI Image Format files can be written either uncompressed or with run length encoding compression and with one or two bytes per pixel per channel. Refer to _i_m_p._h for the supported raster types. _d_i_m_e_n_s_i_o_n Specifies the number of dimensions in the image. A colormap file will have dimension one. A black and white image will have dimension two and an RGB image will have dimension three. _x_S_i_z_e, _y_S_i_z_e Specifies the image size in pixels. _n_u_m_C_h_a_n_n_e_l_s Specifies the number of image color channels. A black and white image has one channel while an RGB image has three channels. _i_m_a_g_e_T_y_p_e Specifies how the image data is to be interpreted. Image data is either actual color values (normal), screen colormap indices (screen) or a colormap (colormap). Refer to _i_m_p._h for the supported image types. _n_a_m_e Specifies a descriptive string for the image. Strings longer than IIIIMMMMPPPP____NNNNAAAAMMMMEEEE____MMMMAAAAXXXX characters will be truncated. Refer to _i_m_p._h for the value of IIIIMMMMPPPP____NNNNAAAAMMMMEEEE____MMMMAAAAXXXX. If this parameter is specified as NNNNUUUULLLLLLLL, the string "no name" will be written into the file. Use the empty string "" to write an empty name string into the image. The _i_m_p_O_p_e_n_E_x_t and _i_m_p_O_p_e_n_F_d_E_x_t functions also open an image file but in addition allow an offset and image cache mode to be specified. The offset is the number of bytes into the file where the image is to be read or written. The cache mode is used only during image reading and specifies how the image data is to be accessed for subsequent reads. The value of the cache mode is ignored when in writing mode (the mode is implicitly IIIIMMMMPPPPNNNNooooCCCCaaaacccchhhheeee). The cache mode may be one of: PPPPaaaaggggeeee 2222 iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIIMMMMPPPPNNNNooooCCCCaaaacccchhhheeee Do not cache the image data. All subsequent image reads will be done from the disk file or descriptor. IIIIMMMMPPPPHHHHeeeeaaaappppCCCCaaaacccchhhheeee Cache the image data in storage allocated from the heap. All subsequent image reads will be done from the data stored in the heap cache. IIIIMMMMPPPPMMMMaaaappppCCCCaaaacccchhhheeee Memory map the image file. All subsequent image reads will use the memory mapping facility to reference the image data. The _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t functions allow reading an SGI Image that is already in memory. Writing of the image is not currently supported by these two functions. The buffer specified in the call to _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t must not be deallocated until _i_m_p_C_l_o_s_e has been called. _i_m_p_C_l_o_s_e closes an SGI Image Format file previously opened by _i_m_p_O_p_e_n or _i_m_p_O_p_e_n_F_d. Among other tasks, _i_m_p_C_l_o_s_e closes the file descriptor associates with image file if appropriate. If the image was opened using _i_m_p_O_p_e_n_F_d or _i_m_p_O_p_e_n_F_d_E_x_t, the file descriptor specified in that function call will be closed by _i_m_p_C_l_o_s_e. _i_m_p_C_l_o_s_e_F_d performs the same function as _i_m_p_C_l_o_s_e but it leaves open the file descriptor associated with the image and returns it in the parameter _f_d_p. It then becomes the responsibility of the caller to close the file descriptor when it is no longer needed. It is essential that either _i_m_p_C_l_o_s_e or _i_m_p_C_l_o_s_e_F_d be called at the completion of writing an SGI Image file so that all buffered data can be written and the image header can be updated. When an image has been opened using _i_m_p_O_p_e_n_B_u_f or _i_m_p_O_p_e_n_B_u_f_E_x_t either close function may be used. If _i_m_p_C_l_o_s_e_F_d is used, -1 is returned as the file descriptor. The _I_M_P_I_m_a_g_e structure contains public and private information about an SGI Image file. This structure is identical both in size and field naming to the _I_M_A_G_E structure defined in the header file _i_m_a_g_e._h included by application that use the _l_i_b_i_m_a_g_e library. While it has been common practice to directly modify the public fields of the image structure, this is not recommended. Macros are defined in _i_m_p._h for manipulating the structure fields. It is strongly recommended that these macros be used to set and get values from the image structure. The _I_M_P_I_m_a_g_e structure is defined as follows. typedef struct _impImage { /******* Public image header information (archived) */ ushort_t imagic; /* SGI Image file magic number */ ushort_t type; /* Raster type (e.g. verbatim, rle) */ ushort_t dim; /* Image dimension */ ushort_t xsize; /* X size (pixels) */ ushort_t ysize; /* Y size (pixels) */ ushort_t zsize; /* Number of channels (e.g. rgb = 3) */ PPPPaaaaggggeeee 3333 iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) __int32_t min; /* Minimum intensity in image */ __int32_t max; /* Maximum intensity in image */ __uint32_t wastebytes; /* Padding */ char name[IMP_NAME_MAX+1]; /* Image name */ __uint32_t colormap; /* Image type (e.g. colormap, normal) */ /******* Private image header information (core use only) */ __int32_t file; ushort_t flags; short dorev; short x; short y; short z; short cnt; short *ptr; short *base; short *tmpbuf; __uint32_t offset; __uint32_t rleend; __uint32_t *rowstart; __int32_t *rowsize; off_t start; IMPCacheMode cache; void* cachebuf; __uint32_t cachesize; off_t cacheoffset; } IMPImage; where _u_s_h_o_r_t__t is _u_n_s_i_g_n_e_d _s_h_o_r_t, ___i_n_t_3_2__t is a 32-bit integer and ___u_i_n_t_3_2__t is a 32-bit unsigned integer. _m_a_g_i_c Magic number identifying this file as an SGI Image Format file. _t_y_p_e Bitwise OR combined code indicating the raster encoding method and the number of bytes per pixel per channel. Currently, SGI Image files support either a verbatim, uncompressed, raster encoding or a run length, compressed, encoding. Both of these encodings are available at one or two bytes per pixel per channel. The header file _i_m_p._h defines codes for all supported combinations of encoding methods and pixel widths. _d_i_m Number of dimensions to the image. A colormap file has dimension one (i.e. length). A black and white image has dimension two (i.e. height and width) and an RGB image has dimension three (i.e. height, width and depth). PPPPaaaaggggeeee 4444 iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) _x_s_i_z_e, _y_s_i_z_e Image size in pixels. _z_s_i_z_e Number of color channels or depth. A black and white image has one channel while an RGB image has three channels. _m_i_n, _m_a_x The minimum and maximum intensity values in the image. These values are the minimum and maximum for all channels combined. _n_a_m_e A descriptive name string for the image. _c_o_l_o_r_m_a_p The image type. Refer to _i_m_p._h for the supported image type codes. The field is named _c_o_l_o_r_m_a_p for compatibility with the _I_M_A_G_E structure used by the _l_i_b_i_m_a_g_e library. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE All image open function return a pointer to an image structure if execution was successful. NNNNUUUULLLLLLLL is returned and _I_M_P_e_r_r_n_o is set if an execution error has occurred. _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d return 0 if execution was successful. -1 is returned and _I_M_P_e_r_r_n_o is set if an execution error has occurred. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS In addition to the system error codes defined in _e_r_r_n_o._h, the following _l_i_b_i_m_p specific error codes may be returned. All image open functions will fail under the following circumstances. IMP_ERR_READWRITE Read/write mode is not supported. IMP_ERR_MEMALLOC Dynamic memory allocation failed. This indicates an out-of-memory condition. IMP_ERR_BADMAGIC Bad magic number in image file header. The file may not be and SGI Image Format file. IMP_ERR_BADRASTER Unrecognized raster encoding method. Refer to _i_m_p._h for supported raster encodings. IMP_ERR_BADIMAGE Unrecognized image type. Refer to _i_m_p._h for supported image types. In addition, _i_m_p_O_p_e_n_F_d and _i_m_p_O_p_e_n_F_d_E_x_t will fail under the following circumstances. IMP_ERR_BADFD The specified file descriptor is invalid. PPPPaaaaggggeeee 5555 iiiimmmmppppOOOOppppeeeennnn((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo iiiimmmmppppOOOOppppeeeennnn((((3333)))) IMP_ERR_SEEK A seek cannot be performed on the specified file descriptor. _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t may also return the following error code. IMP_ERR_NOWRITE Writing mode not allowed by the function. _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d will fail under the following circumstances. IMP_ERR_WRITEFLAG Attempt to write to an image file not opened for writing. IMP_ERR_BADBPP Unsupported bytes per pixel value. Refer to _i_m_p._h for supported BPP values. IMP_ERR_BADIMAGE Unrecognized image type. Refer to _i_m_p._h for supported image types. NNNNOOOOTTTTEEEE The storage for the _I_M_P_I_m_a_g_e structure is allocated by the image open function. This storage is deallocated by the _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d functions. The caller should not explicitly reallocate or deallocate any storage related to the image structure. SSSSEEEEEEEE AAAALLLLSSSSOOOO libimp(3), impReadRow(3), impReadRowB(3), mmap(2) PPPPaaaaggggeeee 6666 
